1 link tagged with all of: ai code generation + documentation + markdown specifications + source of truth
Links
As AI agents generate more code from prompts, the actual intent behind that code gets lost. The author argues teams should treat Markdown specifications as source code, checking them into `/src` alongside generated code so both humans and agents can reference the same source of truth.
- Today's AI-generated code emerges from ephemeral prompt sessions with no persisted specification, unlike traditional compilers that retain source code. Markdown in the codebase should become the canonical specification instead.
- Markdown belongs in `/src` next to code because it keeps intent and implementation together, eliminates scattered documentation across wikis and tickets, and works naturally for both human and agent consumption.
- Tests shouldn't be the specification—they're too ceremonial and low-level for humans to work with effectively. Markdown specs and derived tests should have separate roles.
markdown specifications
ai code generation
source of truth
documentation